SQL Server 2008 : Database Mail - Related Views and Procedures

Viewing the Mail Configuration Objects

The first set of msdb objects we’ll review are those related to system objects such as profiles, profile security, and accounts:

• sysmail_profile— Contains basic profile data, including the unique profile_id, name, description, last_mod_datetime, and last_mod_user name. You execute sysmail_help_profile_sp to retrieve this data by @profile_name or @profile_id.

• sysmail_principalprofile— Contains profile security settings, including the profile_id, associated principal (or user) (principal_SID), profile default status (is_default: 1 for yes or 0 for no), last_mod_datetime, and last_mod_user name. You execute sysmail_help_principalprofile_sp to retrieve this data by @profile_name, @profile_id, @principal_name, or @principal_id (not principal SID). Here’s an example:

  exec msdb.dbo.sysmail_help_principalprofile_sp
      @profile_name='Default SQL 2008 Profile'
  

• sysmail_account— Contains basic account data, including the unique account_id, name, description, email_address, display_name, replyto_address, last_mod_datetime, and last_mod_user name. You execute sysmail_help_account_sp to retrieve this data by @account_id or @account_name.

• sysmail_server— Contains account SMTP server data, including the unique related account_id and servertype, servername, port, server username, server authentication data (credential_id), SSL status (enable_SSL), last_mod_datetime, and last_mod_user name. (sysmail_help_account_sp returns data from this table as well.)

• sysmail_servertype— Contains servertype data for accounts’ servers. (SMTP is the only currently supported type, although it seems this system was built for extensibility, as the columns is_incoming and is_outgoing may leave the door open for adding POP or IMAP servers sometime in the future.) Also includes last_mod_datetime and last_mod_user name. (sysmail_help_account_sp returns data from this table as well.)

  To join sysmail_account, sysmail_server, and sysmail_servertype (as sysmail_help_account_sp seems to do), you can try a query such as the following:

  SELECT *
  FROM msdb.dbo.sysmail_account a
  JOIN msdb.dbo.sysmail_server s
  ON a.account_id = s.account_id
  JOIN msdb.dbo.sysmail_servertype st
  ON st.servertype = s.servertype
  

• sysmail_profileaccount— Maintains the profile-account relationship, including the profile_id, account_id, account priority sequence_number, last_mod_datetime, and last_mod_user name. You execute sysmail_help_profileaccount_sp to retrieve this data by @account_id, @account_name, @profile_id, or @profile_name.

• sysmail_configuration— Contains the system-wide mail configuration settings (paramname, paramvalue, description), and when and by whom each was last modified (last_mod_datetime and last_mod_user name). You execute sysmail_help_configure_sp to query this data by @parameter_name. Here’s an example:

  exec msdb.dbo.sysmail_help_configure_sp
      @parameter_name='accountretrydelay'
  

Viewing Mail Message Data

The second set of msdb objects (and perhaps the more important ones) we’ll review are those used to discover the status of mail messages.

The first thing you need to do is to check on the status of the mail messages you’ve attempted to send, without relying on inboxes to tell you if they’ve been received. Several views in msdb enable this, most of which may be filtered by mail account, sending user, send date, status, and more. To begin this process, you query the view sysmail_allitems, which contains all the data about your messages (subjects, recipients, importance, and so on) as well as send_request_date, sent_date, and sent_status. Here’s an example:

SELECT mailitem_id, subject, sent_status
FROM msdb.dbo.sysmail_allitems
go
mailitem_id subject                                              sent_status
----------------------------------------------------------------------------
1           Database Mail Test                                   sent
2           C. Adams, Contact Info                               sent
3           XAML for HL Touring Seat/Saddle attached.             sent
4           SQL Server Job System: 'Database Mail Test Job' sent

(4 row(s) affected)


					  

Because all these messages have a sent_status of sent, the contents of this recordset are analogous to what you’d find if you queried the view sysmail_sentitems. But suppose your sent_status column read failed. In that case, you’d start by querying the sysmail_faileditems view (a subset of sysmail_allmailitems) in conjunction with sysmail_event_log (which contains the detailed textual reasons why failures have occurred). Here’s an example:

SELECT f.subject, f.mailitem_id, l.description
FROM msdb.dbo.sysmail_event_log l
JOIN msdb.dbo.sysmail_faileditems f
ON f.mailitem_id = l.mailitem_id
WHERE event_type = 'error'
ORDER BY log_date
go
subject               mailitem_id     description
------------------------------------------------------------------------------------
Database Mail Test    3               The mail could not be sent because[...]the
string is not in the form required for an e-mail address

(1 row(s) affected)


					  

Note that the quality of the contents of sysmail_event_log depends on the Log Level system-wide mail configuration setting . The Log File Viewer also uses this table’s contents. To permanently delete its contents, you use the stored procedure sysmail_delete_log_sp.

To query how many messages are queued (waiting to be sent) and for how long, you use the sysmail_unsentitems view. Here’s an example:

SELECT
    mailitem_id,
    subject,
    DATEDIFF(hh, send_request_date, GETDATE()) HoursSinceSendRequest
FROM msdb.dbo.sysmail_unsentitems

If you’re unsure why messages aren’t being sent, you can try the following:

• Execute sysmail_help_queue_sp, whose resulting state column tells the state of the mail transmission queues: INACTIVE (off) or RECEIVES_OCCURRINGmail (outbound) or status (send status) queues, you use the @queue_type parameter. (on). To see the status for only the

• Execute sysmail_help_status_sp, whose resulting Status column tells you the state of Database Mail itself: STOPPED or STARTED.